Explanation

Context

Updating the amount of a Money Account deposit currently fans one logical user action out through multiple nested transaction updates, parent calldata rebuilds, controller publications, and quote generations. In the reference iOS simulator trace, Update/Done to an executable quote took 8.503 seconds:

Relay is a third-party request whose latency varies independently. This proof of concept targets the client-controlled work before and after that request.

What this PR changes

This PR adds generic controller primitives and an explicit Transaction Pay amount-update pipeline.

TransactionController

• Adds updateTransactionCallback, a synchronous messenger action that updates multiple transaction properties atomically against the latest metadata without requiring callers to pass a full, potentially stale transaction object.
• Exports updateEIP7702BatchData, a pure synchronous utility that validates indexed nested-transaction calldata updates, returns a new nested-transaction list, and rebuilds parent EIP-7702 batch calldata once.
• Keeps updateAtomicBatchData as the existing explicit asynchronous API for consumers that require gas estimation, while synchronously clearing stale gas and simulation metadata when new batch calldata is published.

TransactionPayController

• Adds updateAmount, backed by a consumer-provided asynchronous prepareTransactionAmount callback, so transaction-specific amount conversion and calldata construction remain outside the generic controller.
• Validates that the callback returns the complete required nested-update set before publishing anything.
• Uses updateEIP7702BatchData inside updateTransactionCallback to synchronously commit required assets, every nested calldata update, and parent batch calldata in one state update.
• Does not explicitly estimate gas or await simulation before starting quote generation. Existing background TransactionController simulation and gas polling behavior remains unchanged.
• Deduplicates identical in-flight amount intents, aborts superseded intent and quote work, and aborts any existing generic quote request before amount preparation starts.
• Suppresses the TransactionController listener during the synchronous commit so the explicit update starts exactly one quote generation.
• Returns the complete Promise<boolean> for amount preparation and quote generation rather than exposing a separate promise property.

Flow

Before
======
Update/Done
    |
    +--> update approval call --> rebuild parent --> publish
    |                                      `--> quote generation A (superseded)
    |
    `--> update deposit call  --> rebuild parent --> publish
                                           `--> quote generation B --> Relay

After
=====
Update/Done
    |
    `--> abort stale quote work
             |
             `--> prepare complete amount patch
                      |
                      `--> synchronous callback update
                              - required assets
                              - all nested calldata
                              - parent EIP-7702 calldata
                                   |
                                   `--> one quote generation --> Relay

A newer amount aborts the earlier amount preparation and quote request so late results cannot publish stale quotes.

Why start with Money Account deposits?

Money Account deposits expose the amplification clearly: an amount change updates approval and deposit calldata, requires previewDeposit, and then feeds Transaction Pay and EIP-7702/delegation work. The flow is narrow enough to validate behind a Mobile feature flag while retaining the legacy path as a kill switch.

The APIs are intentionally not Money Account-specific. updateTransactionCallback provides generic atomic callback updates, updateEIP7702BatchData provides generic indexed EIP-7702 calldata updates, and Transaction Pay delegates flow-specific preparation to an injected callback.

Benchmark result

A follow-up React Native DevTools trace used the same inferred Update/Done and executable-commit anchors:

The Relay request regressed by 1.011 seconds in the second sample even though this PR does not optimize Relay. Treating Relay as the same 4.108-second contribution in both traces gives a normalized PoC total of 6,426.691 ms, a 2,075.840 ms / 24.4% end-to-end improvement. Client-controlled time fell from 4,394.591 ms to 2,318.751 ms, a 47.2% reduction.

Structural trace evidence:

• 29 → 19 requests in the measured window
• 18 → 11 requests before Relay
• two → one eth_estimateGas calls
• 1,640 ms → 483 ms of pre-request React scheduler time
• 1,091 ms → 313 ms of pre-request render time

These are two simulator traces, not production p50/p95 measurements. Relay latency should continue to be reported separately, and old/new runs should be alternated over multiple samples. The trace predates the final review-driven simplification that removed explicit gas/simulation preparation from the amount-update path, so it should be treated as directional evidence rather than a final-code benchmark.

Correctness and rollout constraints

• The adopting callback must return the complete nested update set.
• Indexed updates are validated before the transaction callback publishes state.
• Required assets, nested calldata, and parent calldata are committed together or not at all.
• The EIP-7702 utility runs inside the callback against current transaction metadata, avoiding stale read-modify-write updates.
• Existing quote work is aborted before asynchronous amount preparation begins; superseded amount and quote results are discarded through abort signals.
• Existing listener-driven and gas-estimating behavior remains available to non-adopting flows; batch calldata updates do not expose stale gas or simulation metadata while estimation is pending.
• The Mobile integration is gated and retains the legacy path.
• Security/privacy review is still required before rollout to confirm whether Sentinel gates execution only or must also gate vendor disclosure.

Future work

• Evaluate explicit metadata for disabling background simulation and gas polling for MetaMask Pay transactions.
• Start live balance and safe capability work earlier and concurrently with transaction-specific preparation.
• Deduplicate or advance remaining capability and metadata reads.
• Add explicit spans around delegation, request construction, normalization, and state publication.
• Collect alternating old/new samples and release profiles on physical iOS and Android devices.
• Validate and incrementally adopt the generic pipeline in other Transaction Pay flows.

Validation

• yarn workspace @metamask/transaction-controller run test
• yarn workspace @metamask/transaction-pay-controller run test — 100% statement, branch, function, and line coverage
• Both changed workspaces build successfully.
• Messenger action type checks pass for both controllers.
• Changelog validation passes for both changed packages.
• yarn lint
• Prettier and git diff --check pass for changed files.

References

• Mobile first-adopter PR: MetaMask/metamask-mobile#33433
• Baseline trace SHA-256: 28e517a73d33db3aa63470f9bc55bdbb47fc61060b09227dce3c5df2d4ae13a9
• PoC trace SHA-256: e80c86da8913924a228627d851ab75965174a30c7607cee1416917aa2c34f

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them